---
title: IDE Installation

description: How to add Pyrefly Language Server and Typechecking to your IDE
---

# Add Pyrefly to your IDE
Pyrefly seamlessly integrates into IDEs with our [VSCode](https://marketplace.visualstudio.com/items?itemName=meta.pyrefly) and [OpenVSX](https://open-vsx.org/extension/meta/pyrefly) extensions. For other editors like vim/emacs, see [other editors](#other-editors).

To see what features are supported by the IDE extension, see the [Supported Features page](../IDE-features).

## Quick start

1. Install the Pyrefly extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=meta.pyrefly) or [Open VSX](https://open-vsx.org/extension/meta/pyrefly).
2. Open any Python file and the extension will activate automatically.

:::tip
Not seeing inlay hints in VS Code? Try setting `editor.inlayHints.enabled` to `true` in your VS Code settings.
:::

:::tip
Want type error squiggles to show up in VS Code? Try setting `python.pyrefly.displayTypeErrors` to `"force-on"` in your VS Code settings, or create a `pyrefly.toml` file in your project root.
:::

## Customization
By default, Pyrefly should work in the IDE with no configuration necessary. But to ensure your project is set up properly, see [configurations](../configuration).

The following configuration options are IDE-specific and exposed as VSCode settings:
- Disable all language services
  - `python.pyrefly.disableLanguageServices` [boolean: false]: By default, Pyrefly will provide both type errors and other language features like go-to definition, intellisense, hover, etc. Set `disableLanguageServices` to `true` to keep type errors from Pyrefly unchanged but use VSCode's Python extension for everything else.
- Disable certain language services
  - `python.pyrefly.disabledLanguageServices` [json: {}]: a config to disable certain lsp methods from pyrefly. For example, if you want go-to definition but not find-references.
- Disable type errors
  - `python.pyrefly.displayTypeErrors` [enum: default, force-on, force-off]: If `'default'`, Pyrefly will only provide type check squiggles in the IDE if your file is covered by a [Pyrefly configuration](../configuration). If `'force-off'`, Pyrefly will never provide type check squiggles in the IDE. If `'force-on'`, Pyrefly will always provide type check squiggles in the IDE.
- Specify a custom Pyrefly Binary (lspPath)
  - `pyrefly.lspPath` [string: '']: If your platform is not supported, you can build pyrefly from source and specify the binary path with the `lspPath` config.
- Use a specific interpreter
  - If the [`Python`](https://marketplace.visualstudio.com/items?itemName=ms-python.python) VSCode extension is installed, [selecting an interpreter](https://code.visualstudio.com/docs/python/environments) will override the interpreter and settings Pyrefly uses to type check your project, even if one is specified in your Pyrefly configuration.
  - `python.defaultInterpreterPath` will override the default interpreter selected by VSCode for your workspace.
- Control hover tooltip links
  - `python.analysis.showHoverGoToLinks` [boolean: true]: Controls whether hover tooltips include "Go to definition" and "Go to type definition" navigation links. Set to `false` for cleaner tooltips with only type information.

## Issues?
If you experience issues with the Pyrefly extension, please create an [issue](https://github.com/facebook/pyrefly/issues) on github.

## Other Editors
Support for other editors is community-driven. If you would like to set this up, please contribute.

### Windsurf, Cursor and Kiro

You can use Pyrefly in your favorite AI editor that supports [OpenVSX](https://open-vsx.org/extension/meta/pyrefly) extensions. Search for "Pyrefly" in the extension marketplace and install it. Similar to VSCode, Pyrefly will automatically activate when you open a Python file.

To avoid conflicts, you should disable other Python language servers by either setting "Language Server: None" in the extension settings or by disabling the Pyright or BasedPyright extensions.

<video
  src="/videos/openvsx.mp4"
  width="720"
  muted
  loop
  autoPlay
  playsInline
  preload="metadata"
/>

### Jetbrains / Pycharm
PyCharm users can enable native Pyrefly support in the settings:
1. Go to **Python | Tools | Pyrefly** in the Settings dialog.
2. Select the **Enable** checkbox.
3. In the Execution mode setting, select how PyCharm should search for the executable:

    **Interpreter** mode: PyCharm searches for an executable installed in your interpreter. To install the Pyrefly package for the selected interpreter, click *Install Pyrefly*.

    **Path** mode: PyCharm searches for an executable in `$PATH`. If the executable is not found, you can specify the path by clicking the  Browse... icon.

4. Select which options should be enabled.

For more information, refer to [PyCharm documentation](https://www.jetbrains.com/help/pycharm/2025.3/lsp-tools.html#pyrefly).

### Neovim

Pyrefly supports native Neovim support through `lspconfig` on Neovim 0.11+. Install and setup Pyrefly using the settings below.

The recommended way to set up Pyrefly in **Neovim 0.11+** is:
1. Install or update the [`neovim/nvim-lspconfig`](https://github.com/neovim/nvim-lspconfig), [`mason-org/mason.nvim`](https://github.com/mason-org/mason.nvim), and [`mason-org/mason-lspconfig.nvim`](https://github.com/mason-org/mason-lspconfig.nvim) plugins with your plugin manager of choice.
2. Add the following to your Neovim `init.lua`:
```lua
require("mason").setup()
require("mason-lspconfig").setup()
```
3. In Neovim, run `:MasonInstall pyrefly` or add `pyrefly` to your `ensure_installed` options:
```lua
require("mason-lspconfig").setup {
  ensure_installed = { "pyrefly" },
}
```

<details>
    <summary>Alternative setups and configurations</summary>

    While the above section describes the fastest way to set up Pyrefly, you may already have a setup or prefer to use other approaches for your lspconfig. Below we describe alternatives to both Pyrefly installation and configuration.

    :::note
    We don't provide instructions for setting up Neovim with versions prior to Neovim 0.11, though Pyrefly can work with them through [`neovim/nvim-lspconfig`](https://github.com/neovim/nvim-lspconfig).
    :::

    <details>
        <summary>Install Pyrefly for Neovim</summary>

        There are two methods we currently support for installing Pyrefly for Neovim:
        1. (recommended) Install the `mason-org/mason.nvim` plugin, which handles installing language services and configuring them easily.
        2. Use a system installation.

        <details>
            <summary>mason.nvim</summary>

            [mason.nvim](https://github.com/mason-org/mason.nvim) is our recommended approach, since it makes Pyrefly and other language servers, linters, and utilities easily available to Neovim.

            :::note
            Installing a binary with Mason will take precedence over other system installations. It might be worth using system installations (including installations in virtual environments) if you need to switch between different versions of Pyrefly for different projects.
            :::

            Install Mason using your Neovim plugin manager of choice, and make sure you call its setup function to make it available.

            To install Pyrefly, run `:MasonInstall pyrefly` in Neovim, and it will be installed! You can install a specific version of Pyrefly with `:MasonInstall pyrefly@<version>`, and manage Mason installations (including per-language-server-specific settings!) with `:Mason`.
        </details>

        <details>
            <summary>System Installations</summary>

            Pyrefly can also work with Neovim's `lspconfig` when using a system installation. This will work as long as the Pyrefly binary you want to use is available on your `$PATH`, which you can check by making sure commands like `pyrefly --help` succeed. If an installation is available on your `$PATH`, continue on to [configure](#configure-pyrefly-for-neovim) below.

            To install Pyrefly, you can use the package manager of your choice. We support `uv`, `pip`, `Cargo`, and anything else that can interface with PyPI (see [Installation](./installation.mdx) for more info).

            :::note
            If you're installing Pyrefly into a virtual environment, please be aware that Pyrefly will only work within Neovim if the virtual environment is activated when you start Neovim.
            :::

            Before moving on, double check that you can access Pyrefly on your `$PATH`. If you can, then continue with [configure](#configure-pyrefly-for-neovim).

            If Pyrefly is not available on your `$PATH`, you can try the following:
            - If you're using a virtual environment, try `source .venv/bin/activate` to ensure your venv is running, then see if `pyrefly` is available.
            - If you're using `uv`, you can ensure `uv`-installed tools are available on your path by running `uv tool update-shell`.
            - Configure `lspconfig` to use a specific executable/command by updating your Pyrefly-specific lspconfig settings. To do this, override the `cmd` configuration option with your command in the configuration section below.
        </details>

    </details>
    <details>
        <summary> Configure Pyrefly for Neovim</summary>

        This section describes how to tell Neovim how Pyrefly can be run, as well as how to override those settings.

        You have two options on how to do this:
        1. (recommended) Install or update the [`neovim/nvim-lspconfig`](https://github.com/neovim/nvim-lspconfig) plugin to get Pyrefly's (and other language servers') default configs. You can override specific settings if you'd like.
        2. Setup your language server manually without installing extra plugins.

        <details>
            <summary>Configs with `neovim/nvim-lspconfig` plugin</summary>

            [`neovim/nvim-lspconfig`](https://github.com/neovim/nvim-lspconfig) is a Neovim plugin acting as a repository of language server settings (a repository of language server settings) installed and updated to get Pyrefly's default configuration.

            We also recommend installing or updating the [mason-org/mason-lspconfig.nvim](https://github.com/mason-org/mason-lspconfig.nvim) plugin if you're using Mason, which provides other nice functionality when using Mason with `lspconfig`. If you install `mason-org/mason-lspconfig.nvim`, be sure to source it in your Neovim config.

            To override specific settings, see `:h vim.lsp.config`. See `:h vim.lsp.Config` and `:h vim.lsp.ClientConfig` for values you can override, and the [`nvim-lspconfig` Pyrefly config](https://github.com/neovim/nvim-lspconfig/blob/master/lsp/pyrefly.lua) for default values.

            Example overriding `cmd` and `filetypes`
            ```lua
            vim.lsp.config('pyrefly', {
                -- example of how to run `uv` installed Pyrefly without adding to your path
                cmd = { 'uvx', 'pyrefly', 'lsp' }
            })
            ```
        </details>

        <details>
            <summary>No-plugin Configs</summary>

            You have the option to setup your language server without
            `neovim/nvim-lspconfig`. Simply copy/modify the Pyrefly defaults
            from
            [`nvim-lspconfig`](https://github.com/neovim/nvim-lspconfig/blob/master/lsp/pyrefly.lua)
            in a block like below.

            **NOTE: This should be in a file under `nvim/lsp/pyrefly.lua`

            ```lua
            ---@type vim.lsp.Config
            return {
              cmd = { "pyrefly", "lsp" },
            }
            ```
        </details>

        :::tip
        [This Youtube tutorial](https://youtu.be/IZnhl121yo0?si=VINhYDEySX48_8GY) explains setting up a language server in more depth and with a more organized setup, so check it out if you want to learn more.
        :::

    </details>

    <details>
        <summary>Enable Pyrefly for Neovim</summary>

        If you've installed Pyrefly with Mason and have `mason-org/mason-lspconfig.nvim` installed, then your language server should just work! You can check by opening a file your language server should cover and running `:checkhealth lsp` to see if it's started. You may need to restart Neovim for any changes made above to take effect.

        Otherwise, to make sure your language servers are activated, be sure to enable them with the syntax below.

        ```lua
        vim.lsp.enable({"pyrefly"})
        ```

        :::tip
        If you're using `init.vim`, you can use a [lua heredoc](https://neovim.io/doc/user/lua.html#%3Alua-heredoc) to execute lua and enable your config.
        :::
    </details>
</details>

### Vim/Neovim + coc.nvim

Ensure the pyrefly is on `$PATH`, add following snippet to your `coc-settings.json`:

```json
"languageserver": {
  "pyrefly": {
    "command": "pyrefly",
    "args": ["lsp"],
    "filetypes": ["python"],
    "rootPatterns": ["pyrefly.toml", "pyproject.toml", ".git"],
  }
},
```

### Vim + ALE
Pull the latest version of ALE and add the following lines to your configuration
to enable Pyrefly in Vim with ALE:
```
let g:ale_linters = {
    ...
  \ 'python': ['pyrefly'],
    ...
  \ }
```

### Emacs

There are several emacs packages that implement the language server protocol; the `eglot` package
is built into recent versions of emacs. You can tell `eglot` to use `pyrefly` (which we assume
is on your `$PATH`) with the following configuration:
```
(add-to-list 'eglot-server-programs
  `((python-ts-mode python-mode) . ("pyrefly" "lsp")))
```

If you are using `use-package`, this command would run inside of the `:config` block; a minimal
example would look like this:
```
(use-package eglot
  :ensure t
  :hook ((python-mode python-ts-mode) . eglot-ensure)
  :config
  (add-to-list 'eglot-server-programs
    `((python-ts-mode python-mode) . ("pyrefly" "lsp"))))
```

### Helix

Ensure that pyrefly is on `$PATH` (If you got Pyrefly using `pip install pyrefly`, it should already be on your path).
Add this snippet to your `languages.toml` file

```toml
[language-server.pyrefly]
command = "pyrefly"
args = ["lsp"]

[[language]]
name = "python"
language-servers = ["pyrefly"]
```

### Sublime

See the documentation [here](https://lsp.sublimetext.io/language_servers/#pyrefly).

### Jupyter Lab

Pyrefly may be used in Jupyter Lab through the [jupyterlab-lsp](https://jupyterlab-lsp.readthedocs.io/en/latest/Installation.html) extension.
